# V4_ULTRA_POLISH_IMPROVEMENT_PLAN

> Generated: 2026-07-10
> Base: v3 Kimi 81/100 (frozen)
> Target: v4 Kimi 90+
> Method: Multi-frame per-scene rendering (NOT static frame + zoompan)

---

## v3 Architecture Review

v3 pipeline: `scenes.json` → 1 static frame per scene → ffmpeg zoompan/pulse → concat → subtitle burn

**Fundamental limitation**: Every clip is a ZOOM/PULSE on a SINGLE static frame. No real animation.
All micro-animations are ffmpeg drawbox hacks with approximate pixel coordinates.

---

## Diagnostic: 8-Dimension Analysis

### 1. Which scenes still feel like PPT?

| Scene | PPT Score | Reason |
|-------|-----------|--------|
| idle_state | 6/10 | Static image with cursor blink overlay — feels like mockup |
| context_reset_state | 7/10 | Static numbers pulse — no real counting animation |
| multi_agent_task_state | 5/10 | **Worst offender**. Progress bar is BAKED into frame at 55%. Clip gen tries to pulse an orange box at approximate Y coordinate. Real agents show progress growth |
| bash_success_state | 7/10 | Green border pulse is cheap effect. Real terminal scrolls line by line |
| write_file_state | 8/10 | Code preview is static. No line-by-line writing feel |
| update_diff_state | 7/10 | Static diff. No red/green line sliding |
| bash_error_state | 6/10 | Red band pulse. No error reveal animation |
| task_progress_state | 7/10 | Static 72%. No counting up |
| final_status_state | 8/10 | Verdict pulse is acceptable but basic |

### 2. Which text is still too small for mobile?

- Subtask titles at font 20 — readable but borderline
- Status bar items at font 16 — too small, need 20+
- Agent meta info (elapsed, tokens) at font 16
- Footer "87% context used" at font 14 — **unreadable on phone**
- SRT subtitles at font 14 — too small

### 3. Which animations are "fake"?

| Animation | Real? | Problem |
|-----------|-------|---------|
| Cursor blink | ⚠️ Partial | Rendered as static white rect in frame. Clip gen does NOT actually blink it — the blink_expr is defined but never applied |
| Progress bar fill | ❌ Fake | 55% is baked into the PNG. Clip gen attempts a drawbox hack over approximate Y=537 which may not match actual layout |
| Token increment | ❌ Fake | 6.7k is static text. Pulse zoom doesn't simulate increment |
| Bash line scroll | ❌ Fake | All lines appear at once. Zoompan scrolls the whole image |
| Error pulse | ⚠️ Weak | Red drawbox at fixed coords. Not tied to actual error content |
| Code writing | ❌ Fake | All 18 code lines appear at once. No incremental reveal |
| Diff lines | ❌ Fake | +12/-3 all visible at once. No progressive reveal |
| Agent finished state | ❌ Missing | Never shown. Scene jumps from running to final |

### 4. Which UI details don't look like real Claude Code?

- **Missing**: `Thought for Xs` indicator
- **Missing**: Tool call cards (`Bash(...)`, `Write(...)`, `Edit(...)`, `Read(...)`)
- **Missing**: Background agent notifications (`Backgrounded agent #2`, `Agent finished · 1m 23s`)
- **Missing**: Real terminal prompt prefix (`$`, `❯`)
- **Missing**: Real Claude Code symbols: `● main`, `◯ general-purpose`
- **Missing**: `ctrl+o to expand` hint
- **Missing**: Context usage percentage with real-looking values (97%, 43%, etc.)
- **Missing**: `Waiting for 2 background agents...` state
- **Weak**: Status bar only shows 3 items, real Claude Code shows more

### 5. Multi-agent: Where is it not real enough?

- Only 1 worker shown (v3 reduced from 2 for clarity)
- No worker lifecycle: running → completing → finished
- Progress bar at static 55% — never moves
- Token count "23.7k" never increments
- No "elapsed" time counter animation
- Subtasks appear all at once, not revealed sequentially
- No "Waiting for..." interlude
- No "Agent finished" notification
- Workers are same size — no visual hierarchy

### 6. Success/failure feedback: is it strong enough?

- Success: green accent bar + green text. OK but no celebration
- Failure: red band + red text. Acceptable but no shake/flash
- **Missing**: Side-by-side before/after comparison
- **Missing**: Error recovery sequence (fail → fix → retry → pass)

### 7. Subtitle overlap issues

- SRT at alignment=2 (bottom center), MarginV=30
- May overlap with status bar / final verdict text
- Multi-agent subtitles at (500, 2000) and (2500, 5500) — these overlap with agent section

### 8. Each scene's viewing focus

| Scene | What to look at? | Is it clear? |
|-------|-----------------|--------------|
| idle | Terminal prompt, recent commands | ✅ |
| context | Token numbers, compression | ⚠️ Numbers pulse but don't count |
| multi_agent | Sub-task tree + Progress bar + Agents | ❌ Too much at once, focus unclear |
| bash | Command output, green success | ⚠️ Lines scroll as one block |
| write | Code being generated | ⚠️ All at once |
| diff | Red/green changes | ⚠️ All at once |
| error | Failure indicators | ⚠️ Pulse is weak |
| final | Verdict, stats | ✅ |

---

## V4 Architecture Change

### From: 1 frame → ffmpeg effects
```
scenes.json → 1 PNG → zoompan/pulse → .mp4
```

### To: Multi-frame sequences → smooth animation
```
scenes.json → render_claude_ui_frames_v4.py
  → scene_idle_001_0000.png ... scene_idle_001_0059.png (60 frames, 2s)
  → scene_multi_agent_001_0000.png ... scene_multi_agent_001_0179.png (180 frames, 6s)
  → ...
  → generate_claude_ui_clips_v4.py (ffmpeg -framerate 30 -i sequence)
  → compose_claude_ui_video_v4.py (concat, subtitles, review)
```

Every frame has incrementally different content:
- Progress bar: 0% → target% across frames
- Token count: 0k → targetK across frames
- Subtask lines: appear one by one
- Code lines: type in progressively
- Diff lines: slide in from left
- Error: flash frame at specific moment
- Agent status: running → complete transition

---

## V4 Scene Design

Target: 40s total, 10 scenes

| # | Scene | Dur | Focus | Animation |
|---|-------|-----|-------|-----------|
| 1 | idle_terminal | 2.5s | Terminal prompt + status bar | Cursor blink, recent commands appear |
| 2 | context_compression | 3s | Token count 85k→32k | Numbers count down, bar fills |
| 3 | multi_agent_launch | 4s | 3 agents spawn, tasks appear | Agents appear one by one, progress bars start |
| 4 | multi_agent_running | 5s | Progress bars + tokens + subtasks grow | Bars fill 0→70%, tokens 0→31k, subtasks reveal |
| 5 | bash_tool_call | 3s | Real Claude Code tool card style | Command types out, lines appear one by one |
| 6 | write_tool_call | 3s | Write tool card with code | Code lines type in progressively |
| 7 | edit_diff_tool | 3.5s | Edit tool with diff | Red/green lines slide in, diff counter |
| 8 | error_tool_call | 3s | Bash error with red flash | Error lines appear, red flash on failure |
| 9 | agent_complete | 4s | 3 agents all done, summary | Status changes running→done, bars hit 100% |
| 10 | final_status | 4s | PASS verdict, stats, frozen badge | Verdict pulses, stats cards slide up |

Total: 35s — room for transitions

---

## V4 Rendering Strategy

### Scene structure in renderer:

```python
for scene in scenes:
    total_frames = int(duration * FPS)
    for frame_i in range(total_frames):
        progress = frame_i / total_frames  # 0.0 → 1.0
        img = render_frame(scene, progress)
        img.save(f"{scene_id}_{frame_i:04d}.png")
```

Each render function receives `progress` (0.0-1.0) and renders content at the appropriate state:
- Progress bars: `current = int(target * progress)`
- Token counts: `current = int(max_tokens * progress)`
- Text lines: `visible_lines = int(total_lines * progress)` — only first N lines drawn
- Cursor: alternating visibility based on frame number
- Agent status: transitions at specific progress thresholds

### Key rendering changes:

1. **render_idle_terminal**: 
   - Recent commands appear one at a time (1 per 0.5s)
   - Cursor blinks every 15 frames
   - Status bar with real Claude Code indicators

2. **render_context_compression**:
   - Token number counts down digit by digit
   - Compression bar fills progressively
   - Animated arrow between old→new

3. **render_multi_agent** scenes:
   - 3 agents: main + 2 workers
   - Worker 1: progress 0→100%, tokens 0→31.4k, elapsed 0→47s
   - Worker 2: progress 0→62%, tokens 0→18.2k, elapsed 0→32s
   - Subtask lines reveal one by one (4 subtasks, staggered)
   - "Waiting for 2 background agents..." state text
   - Agent finished notification at end

4. **render_bash_tool_call**:
   - Command prompt appears first, then output lines appear one per ~0.3s
   - Green success indicator pulses at end

5. **render_write_tool_call**:
   - "Write(...) 84 lines" header
   - Code lines appear incrementally (18 lines across 3s)
   - Line counter increments

6. **render_edit_diff**:
   - `Edit(...)` header with +12/-3 counter
   - Red lines slide in from left, green lines from right
   - Counter counts up

7. **render_error_tool_call**:
   - Command appears, then error lines appear line by line
   - Red flash at the moment FAILED appears
   - Warning icon pulses

8. **render_agent_complete**:
   - All agents show ✓ done
   - Progress bars hit 100% with green glow
   - Summary like "3 agents · 47s · 51.2k tokens"

9. **render_final_status**:
   - Verdict "PASS" with scale-up animation
   - Stats cards: 5 files, 42s, 12.3k tokens
   - "STATUS=V4_ULTRA_READY" badge
   - "Kimi target 90+" badge

---

## V4 Claude Code UI Details to Add

### Status Bar (bottom):
```
● main                                          bypass permissions on  
◯ general-purpose                               shift+tab to cycle
                                                ↓ to manage tools
                                                97% context used
```

### Tool Call Cards:
```
Bash(
  $ python scripts/run_pipeline.py --mode full
  [1/5] Loading... OK
  [2/5] Validating... OK
  → Status: completed (exit 0)
)

Write(
  src/quality_gate.py
  84 lines written
  → Status: created
)

Edit(
  src/quality_gate.py
  +12 / -3 lines
  → Status: applied
)
```

### Agent Status Indicators:
```
● main — orchestrator             active    00:47   12.3k tokens  ████████░░ 100%
◯ general-purpose — worker        running   00:22   23.7k tokens  ████░░░░░░  55%
◯ code-writer — worker            running   00:15    8.2k tokens  ██░░░░░░░░  28%
```

### Lifecycle States:
- `spawning` → `running` → `finishing` → `completed`
- Background: `Waiting for 2 background agents...`
- Completion: `Agent finished · 1m 23s · 31.2k tokens`

---

## Implementation Priority

1. ✅ Create directory structure (Step 1)
2. 📝 Write V4_IMPROVEMENT_PLAN.md (this file)
3. 📝 Rewrite scenes.json for V4 (Step 3)
4. 📝 Rewrite render_claude_ui_frames.py — multi-frame (Step 4)
5. 📝 Rewrite generate_claude_ui_clips.py — frame sequences (Step 5)
6. 📝 Rewrite compose_claude_ui_video.py — V4 composition (Step 6)
7. 🚀 Run pipeline (Step 7)
8. 📊 Deploy portal + Kimi audit (Step 8)

---

## Success Criteria

| Metric | v3 | v4 Target |
|--------|-----|-----------|
| Kimi score | 81 | 90+ |
| Mobile readability | 8.5/10 | 9/10 |
| Claude Code real feel | 7.5/10 | 9/10 |
| Multi-agent realism | 6/10 | 9/10 |
| Animation realness | 7/10 | 9/10 |
| PPT感消除 | 8/10 | 9/10 (≤2/10 PPT) |
| Total duration | 38s | 35-40s |